home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Tool Chest / Dev.CD Aug 98 TC.toast / Tool Chest / Development Kits / MPW etc. / MPW-GM / Interfaces&Libraries / Interfaces / PInterfaces / NetSprocket.p < prev    next >
Encoding:
Text File  |  1998-02-17  |  14.1 KB  |  398 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        NetSprocket.p
  3.  
  4.      Contains:    Games Sprockets: NetSprocket interfaces
  5.  
  6.      Version:    Technology:    NetSprocket 1.0.2
  7.                  Release:    Universal Interfaces 3.1
  8.  
  9.      Copyright:    © 1996-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT NetSprocket;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __NETSPROCKET__}
  28. {$SETC __NETSPROCKET__ := 1}
  29.  
  30. {$I+}
  31. {$SETC NetSprocketIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __CONDITIONALMACROS__}
  35. {$I ConditionalMacros.p}
  36. {$ENDC}
  37.  
  38. {$IFC TARGET_OS_MAC }
  39. {$IFC UNDEFINED __MACTYPES__}
  40. {$I MacTypes.p}
  41. {$ENDC}
  42. {$IFC UNDEFINED __EVENTS__}
  43. {$I Events.p}
  44. {$ENDC}
  45.  
  46. {$IFC UNDEFINED __OPENTRANSPORT__}
  47. {$I OpenTransport.p}
  48. {$ENDC}
  49. {$IFC UNDEFINED __OPENTPTINTERNET__}
  50. {$I OpenTptInternet.p}
  51. {$ENDC}
  52.  
  53. {$ENDC}  {TARGET_OS_MAC}
  54.  
  55.  
  56. {$PUSH}
  57. {$ALIGN POWER}
  58. {$LibExport+}
  59.  
  60. {$IFC TARGET_OS_MAC }
  61.  
  62. CONST
  63.     kNSpMaxPlayerNameLen        = 31;
  64.     kNSpMaxGroupNameLen            = 31;
  65.     kNSpMaxPasswordLen            = 31;
  66.     kNSpMaxGameNameLen            = 31;
  67.     kNSpMaxDefinitionStringLen    = 255;
  68.  
  69.  
  70. { NetSprocket basic types }
  71.  
  72. TYPE
  73.     NSpGameReference = ^LONGINT;
  74.     NSpProtocolReference = ^LONGINT;
  75.     NSpProtocolListReference = ^LONGINT;
  76.     NSpAddressReference = ^LONGINT;
  77.     NSpEventCode                        = SInt32;
  78.     NSpGameID                            = SInt32;
  79.     NSpPlayerID                            = SInt32;
  80.     NSpGroupID                            = NSpPlayerID;
  81.     NSpPlayerType                        = UInt32;
  82.     NSpFlags                            = SInt32;
  83.     NSpPlayerName                        = Str31;
  84. { Individual player info }
  85.     NSpPlayerInfoPtr = ^NSpPlayerInfo;
  86.     NSpPlayerInfo = RECORD
  87.         id:                        NSpPlayerID;
  88.         playerType:                NSpPlayerType;                            {  "type" in C }
  89.         name:                    Str31;
  90.         groupCount:                UInt32;
  91.         groups:                    ARRAY [0..0] OF NSpGroupID;
  92.     END;
  93.  
  94. { list of all players }
  95.     NSpPlayerEnumerationPtr = ^NSpPlayerEnumeration;
  96.     NSpPlayerEnumeration = RECORD
  97.         count:                    UInt32;
  98.         playerInfo:                ARRAY [0..0] OF NSpPlayerInfoPtr;
  99.     END;
  100.  
  101. { Individual group info }
  102.     NSpGroupInfoPtr = ^NSpGroupInfo;
  103.     NSpGroupInfo = RECORD
  104.         id:                        NSpGroupID;
  105.         playerCount:            UInt32;
  106.         players:                ARRAY [0..0] OF NSpPlayerID;
  107.     END;
  108.  
  109. { List of all groups }
  110.     NSpGroupEnumerationPtr = ^NSpGroupEnumeration;
  111.     NSpGroupEnumeration = RECORD
  112.         count:                    UInt32;
  113.         groups:                    ARRAY [0..0] OF NSpGroupInfoPtr;
  114.     END;
  115.  
  116. { Topology types }
  117.     NSpTopology                            = UInt32;
  118.  
  119. CONST
  120.     kNSpClientServer            = $00000001;
  121.  
  122. { Game information }
  123.  
  124. TYPE
  125.     NSpGameInfoPtr = ^NSpGameInfo;
  126.     NSpGameInfo = RECORD
  127.         maxPlayers:                UInt32;
  128.         currentPlayers:            UInt32;
  129.         currentGroups:            UInt32;
  130.         topology:                NSpTopology;
  131.         reserved:                UInt32;
  132.         name:                    Str31;
  133.         password:                Str31;
  134.     END;
  135.  
  136. { Structure used for sending and receiving network messages }
  137.     NSpMessageHeaderPtr = ^NSpMessageHeader;
  138.     NSpMessageHeader = RECORD
  139.         version:                UInt32;                                    {  Used by NetSprocket.  Don't touch this  }
  140.         what:                    SInt32;                                    {  The kind of message (e.g. player joined)  }
  141.         from:                    NSpPlayerID;                            {  ID of the sender  }
  142.         toID:                    NSpPlayerID;                            {  (player or group) id of the intended recipient (was "to)  }
  143.         id:                        UInt32;                                    {  Unique ID for this message & (from) player  }
  144.         when:                    UInt32;                                    {  Timestamp for the message  }
  145.         messageLen:                UInt32;                                    {  Bytes of data in the entire message (including the header)  }
  146.     END;
  147.  
  148. { NetSprocket-defined message structures }
  149.     NSpErrorMessagePtr = ^NSpErrorMessage;
  150.     NSpErrorMessage = RECORD
  151.         header:                    NSpMessageHeader;
  152.         error:                    OSStatus;
  153.     END;
  154.  
  155.     NSpJoinRequestMessagePtr = ^NSpJoinRequestMessage;
  156.     NSpJoinRequestMessage = RECORD
  157.         header:                    NSpMessageHeader;
  158.         name:                    Str31;
  159.         password:                Str31;
  160.         theType:                UInt32;
  161.         customDataLen:            UInt32;
  162.         customData:                SInt8;
  163.     END;
  164.  
  165.     NSpJoinApprovedMessagePtr = ^NSpJoinApprovedMessage;
  166.     NSpJoinApprovedMessage = RECORD
  167.         header:                    NSpMessageHeader;
  168.     END;
  169.  
  170.     NSpJoinDeniedMessagePtr = ^NSpJoinDeniedMessage;
  171.     NSpJoinDeniedMessage = RECORD
  172.         header:                    NSpMessageHeader;
  173.         reason:                    Str255;
  174.     END;
  175.  
  176.     NSpPlayerJoinedMessagePtr = ^NSpPlayerJoinedMessage;
  177.     NSpPlayerJoinedMessage = RECORD
  178.         header:                    NSpMessageHeader;
  179.         playerCount:            UInt32;
  180.         playerInfo:                NSpPlayerInfo;
  181.     END;
  182.  
  183.     NSpPlayerLeftMessagePtr = ^NSpPlayerLeftMessage;
  184.     NSpPlayerLeftMessage = RECORD
  185.         header:                    NSpMessageHeader;
  186.         playerCount:            UInt32;
  187.         playerID:                NSpPlayerID;
  188.         playerName:                NSpPlayerName;
  189.     END;
  190.  
  191.     NSpHostChangedMessagePtr = ^NSpHostChangedMessage;
  192.     NSpHostChangedMessage = RECORD
  193.         header:                    NSpMessageHeader;
  194.         newHost:                NSpPlayerID;
  195.     END;
  196.  
  197.     NSpGameTerminatedMessagePtr = ^NSpGameTerminatedMessage;
  198.     NSpGameTerminatedMessage = RECORD
  199.         header:                    NSpMessageHeader;
  200.     END;
  201.  
  202. { Different kinds of messages.  These can NOT be bitwise ORed together }
  203.  
  204. CONST
  205.     kNSpSendFlag_Junk            = $00100000;                    {  will be sent (try once) when there is nothing else pending  }
  206.     kNSpSendFlag_Normal            = $00200000;                    {  will be sent immediately (try once)  }
  207.     kNSpSendFlag_Registered        = $00400000;                    {  will be sent immediately (guaranteed, in order)  }
  208.  
  209.  
  210. { Options for message delivery.  These can be bitwise ORed together with each other,
  211.         as well as with ONE of the above }
  212.     kNSpSendFlag_FailIfPipeFull    = $00000001;
  213.     kNSpSendFlag_SelfSend        = $00000002;
  214.     kNSpSendFlag_Blocking        = $00000004;
  215.  
  216.  
  217. { Options for Hosting Joining, and Deleting games }
  218.     kNSpGameFlag_DontAdvertise    = $00000001;
  219.     kNSpGameFlag_ForceTerminateGame = $00000002;
  220.  
  221. { Message "what" types }
  222. { Apple reserves all negative "what" values (anything with bit 32 set) }
  223.     kNSpSystemMessagePrefix        = $80000000;
  224.     kNSpError                    = $FFFFFFFF;
  225.     kNSpJoinRequest                = $80000001;
  226.     kNSpJoinApproved            = $80000002;
  227.     kNSpJoinDenied                = $80000003;
  228.     kNSpPlayerJoined            = $80000004;
  229.     kNSpPlayerLeft                = $80000005;
  230.     kNSpHostChanged                = $80000006;
  231.     kNSpGameTerminated            = $80000007;
  232.  
  233.  
  234. { Special TPlayerIDs  for sending messages }
  235.     kNSpAllPlayers                = $00000000;
  236.     kNSpHostOnly                = $FFFFFFFF;
  237.  
  238.  
  239. { NetSprocket Error Codes }
  240.     kNSpInitializationFailedErr    = -30360;
  241.     kNSpAlreadyInitializedErr    = -30361;
  242.     kNSpTopologyNotSupportedErr    = -30362;
  243.     kNSpPipeFullErr                = -30364;
  244.     kNSpHostFailedErr            = -30365;
  245.     kNSpProtocolNotAvailableErr    = -30366;
  246.     kNSpInvalidGameRefErr        = -30367;
  247.     kNSpInvalidParameterErr        = -30369;
  248.     kNSpOTNotPresentErr            = -30370;
  249.     kNSpOTVersionTooOldErr        = -30371;
  250.     kNSpMemAllocationErr        = -30373;
  251.     kNSpAlreadyAdvertisingErr    = -30374;
  252.     kNSpNotAdvertisingErr        = -30376;
  253.     kNSpInvalidAddressErr        = -30377;
  254.     kNSpFreeQExhaustedErr        = -30378;
  255.     kNSpRemovePlayerFailedErr    = -30379;
  256.     kNSpAddressInUseErr            = -30380;
  257.     kNSpFeatureNotImplementedErr = -30381;
  258.     kNSpNameRequiredErr            = -30382;
  259.     kNSpInvalidPlayerIDErr        = -30383;
  260.     kNSpInvalidGroupIDErr        = -30384;
  261.     kNSpNoPlayersErr            = -30385;
  262.     kNSpNoGroupsErr                = -30386;
  263.     kNSpNoHostVolunteersErr        = -30387;
  264.     kNSpCreateGroupFailedErr    = -30388;
  265.     kNSpAddPlayerFailedErr        = -30389;
  266.     kNSpInvalidDefinitionErr    = -30390;
  267.     kNSpInvalidProtocolRefErr    = -30391;
  268.     kNSpInvalidProtocolListErr    = -30392;
  269.     kNSpTimeoutErr                = -30393;
  270.     kNSpGameTerminatedErr        = -30394;
  271.     kNSpConnectFailedErr        = -30395;
  272.     kNSpSendFailedErr            = -30396;
  273.     kNSpJoinFailedErr            = -30399;
  274.  
  275.  
  276.  
  277.  
  278. {***********************  Initialization  ***********************}
  279. FUNCTION NSpInitialize(inStandardMessageSize: UInt32; inBufferSize: UInt32; inQElements: UInt32; inGameID: NSpGameID; inTimeout: UInt32): OSStatus; C;
  280.  
  281.  
  282.  
  283. {*************************  Protocols  *************************}
  284. { Programmatic protocol routines }
  285. FUNCTION NSpProtocol_New(inDefinitionString: ConstCStringPtr; VAR outReference: NSpProtocolReference): OSStatus; C;
  286. PROCEDURE NSpProtocol_Dispose(inProtocolRef: NSpProtocolReference); C;
  287. FUNCTION NSpProtocol_ExtractDefinitionString(inProtocolRef: NSpProtocolReference; outDefinitionString: CStringPtr): OSStatus; C;
  288.  
  289. { Protocol list routines }
  290. FUNCTION NSpProtocolList_New(inProtocolRef: NSpProtocolReference; VAR outList: NSpProtocolListReference): OSStatus; C;
  291. PROCEDURE NSpProtocolList_Dispose(inProtocolList: NSpProtocolListReference); C;
  292. FUNCTION NSpProtocolList_Append(inProtocolList: NSpProtocolListReference; inProtocolRef: NSpProtocolReference): OSStatus; C;
  293. FUNCTION NSpProtocolList_Remove(inProtocolList: NSpProtocolListReference; inProtocolRef: NSpProtocolReference): OSStatus; C;
  294. FUNCTION NSpProtocolList_RemoveIndexed(inProtocolList: NSpProtocolListReference; inIndex: UInt32): OSStatus; C;
  295. FUNCTION NSpProtocolList_GetCount(inProtocolList: NSpProtocolListReference): UInt32; C;
  296. FUNCTION NSpProtocolList_GetIndexedRef(inProtocolList: NSpProtocolListReference; inIndex: UInt32): NSpProtocolReference; C;
  297.  
  298. { Helpers }
  299. FUNCTION NSpProtocol_CreateAppleTalk(inNBPName: Str31; inNBPType: Str31; inMaxRTT: UInt32; inMinThruput: UInt32): NSpProtocolReference; C;
  300. FUNCTION NSpProtocol_CreateIP(inPort: InetPort; inMaxRTT: UInt32; inMinThruput: UInt32): NSpProtocolReference; C;
  301.  
  302. {**********************  Human Interface  ***********************}
  303.  
  304. TYPE
  305. {$IFC TYPED_FUNCTION_POINTERS}
  306.     NSpEventProcPtr = FUNCTION(VAR inEvent: EventRecord): BOOLEAN;
  307. {$ELSEC}
  308.     NSpEventProcPtr = ProcPtr;
  309. {$ENDC}
  310.  
  311. FUNCTION NSpDoModalJoinDialog(inGameType: Str31; inEntityListLabel: Str255; VAR ioName: Str31; VAR ioPassword: Str31; inEventProcPtr: NSpEventProcPtr): NSpAddressReference; C;
  312. FUNCTION NSpDoModalHostDialog(ioProtocolList: NSpProtocolListReference; VAR ioGameName: Str31; VAR ioPlayerName: Str31; VAR ioPassword: Str31; inEventProcPtr: NSpEventProcPtr): BOOLEAN; C;
  313.  
  314. {********************  Hosting and Joining  *********************}
  315. FUNCTION NSpGame_Host(VAR outGame: NSpGameReference; inProtocolList: NSpProtocolListReference; inMaxPlayers: UInt32; inGameName: Str31; inPassword: Str31; inPlayerName: Str31; inPlayerType: NSpPlayerType; inTopology: NSpTopology; inFlags: NSpFlags): OSStatus; C;
  316. FUNCTION NSpGame_Join(VAR outGame: NSpGameReference; inAddress: NSpAddressReference; inName: Str31; inPassword: Str31; inType: NSpPlayerType; inCustomData: UNIV Ptr; inCustomDataLen: UInt32; inFlags: NSpFlags): OSStatus; C;
  317. FUNCTION NSpGame_EnableAdvertising(inGame: NSpGameReference; inProtocol: NSpProtocolReference; inEnable: BOOLEAN): OSStatus; C;
  318. FUNCTION NSpGame_Dispose(inGame: NSpGameReference; inFlags: NSpFlags): OSStatus; C;
  319. FUNCTION NSpGame_GetInfo(inGame: NSpGameReference; VAR ioInfo: NSpGameInfo): OSStatus; C;
  320. {*************************  Messaging  *************************}
  321. FUNCTION NSpMessage_Send(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader; inFlags: NSpFlags): OSStatus; C;
  322. FUNCTION NSpMessage_Get(inGame: NSpGameReference): NSpMessageHeaderPtr; C;
  323. PROCEDURE NSpMessage_Release(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader); C;
  324. { Helpers }
  325. FUNCTION NSpMessage_SendTo(inGame: NSpGameReference; inTo: NSpPlayerID; inWhat: SInt32; inData: UNIV Ptr; inDataLen: UInt32; inFlags: NSpFlags): OSStatus; C;
  326.  
  327. {********************  Player Information  *********************}
  328. FUNCTION NSpPlayer_GetMyID(inGame: NSpGameReference): NSpPlayerID; C;
  329. FUNCTION NSpPlayer_GetInfo(inGame: NSpGameReference; inPlayerID: NSpPlayerID; VAR outInfo: NSpPlayerInfoPtr): OSStatus; C;
  330. PROCEDURE NSpPlayer_ReleaseInfo(inGame: NSpGameReference; inInfo: NSpPlayerInfoPtr); C;
  331. FUNCTION NSpPlayer_GetEnumeration(inGame: NSpGameReference; VAR outPlayers: NSpPlayerEnumerationPtr): OSStatus; C;
  332. PROCEDURE NSpPlayer_ReleaseEnumeration(inGame: NSpGameReference; inPlayers: NSpPlayerEnumerationPtr); C;
  333. FUNCTION NSpPlayer_GetRoundTripTime(inGame: NSpGameReference; inPlayer: NSpPlayerID): UInt32; C;
  334. FUNCTION NSpPlayer_GetThruput(inGame: NSpGameReference; inPlayer: NSpPlayerID): UInt32; C;
  335.  
  336. {********************  Group Management  *********************}
  337. FUNCTION NSpGroup_New(inGame: NSpGameReference; VAR outGroupID: NSpGroupID): OSStatus; C;
  338. FUNCTION NSpGroup_Dispose(inGame: NSpGameReference; inGroupID: NSpGroupID): OSStatus; C;
  339. FUNCTION NSpGroup_AddPlayer(inGame: NSpGameReference; inGroupID: NSpGroupID; inPlayerID: NSpPlayerID): OSStatus; C;
  340. FUNCTION NSpGroup_RemovePlayer(inGame: NSpGameReference; inGroupID: NSpGroupID; inPlayerID: NSpPlayerID): OSStatus; C;
  341. FUNCTION NSpGroup_GetInfo(inGame: NSpGameReference; inGroupID: NSpGroupID; VAR outInfo: NSpGroupInfoPtr): OSStatus; C;
  342. PROCEDURE NSpGroup_ReleaseInfo(inGame: NSpGameReference; inInfo: NSpGroupInfoPtr); C;
  343. FUNCTION NSpGroup_GetEnumeration(inGame: NSpGameReference; VAR outGroups: NSpGroupEnumerationPtr): OSStatus; C;
  344. PROCEDURE NSpGroup_ReleaseEnumeration(inGame: NSpGameReference; inGroups: NSpGroupEnumerationPtr); C;
  345.  
  346. {*************************  Utilities  **************************}
  347. FUNCTION NSpGetVersion: NumVersion; C;
  348. PROCEDURE NSpClearMessageHeader(VAR inMessage: NSpMessageHeader); C;
  349. FUNCTION NSpGetCurrentTimeStamp(inGame: NSpGameReference): UInt32; C;
  350. FUNCTION NSpConvertOTAddrToAddressReference(VAR inAddress: OTAddress): NSpAddressReference; C;
  351. FUNCTION NSpConvertAddressReferenceToOTAddr(inAddress: NSpAddressReference): OTAddressPtr; C;
  352. PROCEDURE NSpReleaseAddressReference(inAddress: NSpAddressReference); C;
  353.  
  354. {*********************** Advanced/Async routines ***************}
  355.  
  356. TYPE
  357. {$IFC TYPED_FUNCTION_POINTERS}
  358.     NSpCallbackProcPtr = PROCEDURE(inGame: NSpGameReference; inContext: UNIV Ptr; inCode: NSpEventCode; inStatus: OSStatus; inCookie: UNIV Ptr);
  359. {$ELSEC}
  360.     NSpCallbackProcPtr = ProcPtr;
  361. {$ENDC}
  362.  
  363. FUNCTION NSpInstallCallbackHandler(inHandler: NSpCallbackProcPtr; inContext: UNIV Ptr): OSStatus; C;
  364.  
  365.  
  366. TYPE
  367. {$IFC TYPED_FUNCTION_POINTERS}
  368.     NSpJoinRequestHandlerProcPtr = FUNCTION(inGame: NSpGameReference; VAR inMessage: NSpJoinRequestMessage; inContext: UNIV Ptr; VAR outReason: Str255): BOOLEAN;
  369. {$ELSEC}
  370.     NSpJoinRequestHandlerProcPtr = ProcPtr;
  371. {$ENDC}
  372.  
  373. FUNCTION NSpInstallJoinRequestHandler(inHandler: NSpJoinRequestHandlerProcPtr; inContext: UNIV Ptr): OSStatus; C;
  374.  
  375.  
  376. TYPE
  377. {$IFC TYPED_FUNCTION_POINTERS}
  378.     NSpMessageHandlerProcPtr = FUNCTION(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader; inContext: UNIV Ptr): BOOLEAN;
  379. {$ELSEC}
  380.     NSpMessageHandlerProcPtr = ProcPtr;
  381. {$ENDC}
  382.  
  383. FUNCTION NSpInstallAsyncMessageHandler(inHandler: NSpMessageHandlerProcPtr; inContext: UNIV Ptr): OSStatus; C;
  384.  
  385.  
  386. {$ENDC}  {TARGET_OS_MAC}
  387.  
  388. {$ALIGN RESET}
  389. {$POP}
  390.  
  391. {$SETC UsingIncludes := NetSprocketIncludes}
  392.  
  393. {$ENDC} {__NETSPROCKET__}
  394.  
  395. {$IFC NOT UsingIncludes}
  396.  END.
  397. {$ENDC}
  398.